Skip to content

feat(cli): align PROXY Protocol configuration with node_listen and ssl.listen, add IPv6 support #12859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
twellck wants to merge 6 commits into
base: master
Choose a base branch
from
Open

feat(cli): align PROXY Protocol configuration with node_listen and ssl.listen, add IPv6 support #12859

twellck wants to merge 6 commits into from

Conversation

@twellck
Copy link

@twellck twellck commented Jan 5, 2026 •
edited
Loading

Description

This pull request aligns the configuration and handling of PROXY Protocol listen ports with the structure used for node_listen and ssl.listen. It adds support for specifying multiple ports and IP addresses (including IPv6), introduces schema validation improvements, ensures backward compatibility with legacy options, and updates documentation.

Key Changes:

Configuration and Schema Improvements:

  • Added support for proxy_protocol.listen_http and proxy_protocol.listen_https as new configuration options.
    • These options allow specifying multiple ports and IP addresses (including IPv6) for PROXY Protocol.
    • New schema validation supports integers, objects, and arrays for port and IP address definitions.
  • Deprecated proxy_protocol.listen_http_port and proxy_protocol.listen_https_port fields for PROXY Protocol while ensuring backward compatibility.
  • Updated config.yaml.example to document the new structure and usage patterns for PROXY Protocol listen options.

Backward Compatibility & Warnings:

  • CLI logic detects the use of deprecated proxy_protocol.listen_http_port and proxy_protocol.listen_https_port fields, issuing warnings, and internally treats them the same as the new configuration (only when legacy fields are present).

Template, Runtime, and IPv6 Support:

  • Updated the Nginx configuration template (ngx_tpl.lua) to use listen_http and listen_https fields.
  • Ensures IPv6 support for PROXY Protocol by dynamically generating additional Nginx listen directives for IPv6 addresses.

Documentation Updates:

  • Example and inline documentation updated to illustrate:
    • Migration from listen_http_port and listen_https_port to listen_http/listen_https.
    • How to specify multiple ports and use specific IPv4/IPv6 bindings.

Testing Enhancements:

  • Added test scenarios for new and legacy configurations, including:
    • Tests for backward compatibility with proxy_protocol.listen_http_port and proxy_protocol.listen_https_port.
    • Validations for the new listen_http and listen_https formats, IPv4/IPv6 combinations, and support for QUIC/HTTP3.
    • Additional tests for unusual inputs, such as unformatted or malformed IPv6 literals.

Which issue(s) this PR fixes:

Fixes #12828

Checklist

  • I have explained the need for this PR and the problem it solves.
  • I have explained the changes or the new features added to this PR.
  • I have added tests corresponding to this change.
  • I have updated the documentation to reflect this change.
  • I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first).

Notes for Reviewers

  • This PR focuses on improving user flexibility and extending IPv6 support for PROXY Protocol configurations.
  • Provides backward-compatible changes to preserve legacy functionality while guiding users toward the new configuration structure.
  • Suggested areas for additional review:
    • Schema changes and edge case validation.
    • Adequacy of tests, particularly for IPv6 bindings and legacy support.

Note: AI helped format this Pull Request.

@dosubot dosubot bot added size:XL This PR changes 500-999 lines, ignoring generated files. enhancement New feature or request labels Jan 5, 2026
@twellck twellck mentioned this pull request Jan 5, 2026
Open
@Baoyuantop
Copy link
Contributor

Baoyuantop commented Jan 7, 2026

Hi @twellck, For the original problem, we only needed to add IPv6 listening to the template; the current modifications are too complex.

{% if proxy_protocol and proxy_protocol.listen_http_port then %}
listen {* proxy_protocol.listen_http_port *} default_server proxy_protocol;
{% if enable_ipv6 then %}
listen [::]:{* proxy_protocol.listen_http_port *} default_server proxy_protocol;
{% end %}
{% end %}

@Baoyuantop Baoyuantop added the wait for update wait for the author's response in this issue/PR label Jan 7, 2026
@twellck
Copy link
Author

twellck commented Jan 7, 2026 •
edited
Loading

Hi @Baoyuantop,

Thank you for the comment!

While the proposed approach would indeed address the immediate issue, I believe it treats the symptom rather than the root cause. My current implementation attempts to address the underlying problem by introducing some standardisation to how listeners are managed going forward.

Adding IPv6 listening directly to the template would further fragment how listeners (node_listen, proxy_protocol.listen_http_port, control/admin/prometheus, etc.) are managed in the APISIX and Nginx configuration. Each of these currently relies on slightly different approaches for defining listener behavior. This fragmentation not only increases maintenance complexity but also limits the ability to provide feature parity across all listening definitions.

My proposed solution is fully backward-compatible, based on regression testing, and builds on the established patterns for node_listen and ssl.listen in APISIX (reworked into reusable functions). By leveraging these existing structures, my hope is to reduce ongoing maintenance efforts while making future listener functionality easier to extend.

For now, this PR focuses specifically on standardising proxy_protocol to keep the changes targeted and manageable. However, I’d be happy to explore extending this standardisation approach to other listeners like admin, control, and prometheus in the Nginx configuration in the future, if that’s something the team sees value in.

I understand that this PR addresses more than the specific issue, but I believe it’s worth considering how we could make Nginx configuration more standardised and maintainable for both developers and deployers of APISIX over time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

enhancement New feature or request size:XL This PR changes 500-999 lines, ignoring generated files. user responded wait for update wait for the author's response in this issue/PR

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

bug: proxy_protocol listeners fail to bind IPv6 even when enable_ipv6: true

2 participants

@twellck @Baoyuantop